@startuml UC03_sequence
!theme plain
hide footbox
skinparam sequenceMessageAlign center
skinparam responseMessageBelowArrow true
skinparam BoxPadding 10
autonumber

title UC-03 - Avoid obstacle (forward blocked, not surrounded)\n(sequence diagram)

actor "Home user\n(beneficiary)" as User
participant "Obstacle sensors" as Obs
box "Roomba RVC control software\n(inside the SSD black box)" #E8F4FF
  participant "perception:\nObstaclePerceptionContext" as Perception
  participant "navigation:\nNavigationAndEscapeCoordinator" as Nav
  participant "cleaning:\nSurfaceCleaningController" as Clean
end box
participant "Wheel motors\n(left, right)" as Motors
participant "Cleaning hardware" as CleanHW

note over User, Clean : after UC-01

alt [E1 sensor ambiguity]
  Obs -> Perception : ObstacleStateChanged(ambiguous)
  Perception -> Nav : FusedObstacleSnapshot(ambiguous)
  note over Perception, Nav : next: UC-05 or UC-08 (TBD)
else [typical or A1 or A2]
  alt [A2 multiple adjustments]
    loop [forward clears then re-blocks]
      Obs -> Perception : ObstacleStateChanged(forwardBlockedNotSurrounded)
      Perception -> Nav : FusedObstacleSnapshot(forwardBlocked, notSurrounded)
      Nav -> Clean : SuspendCleaningForManeuver()
      Clean -> CleanHW : CleaningCommand(suspend)
      alt [typical prefer right]
        Nav -> Motors : MotionCommand(turnRight)
      else [A1 right not valid]
        Nav -> Motors : MotionCommand(turnLeft)
      end
      Obs -> Perception : ObstacleStateChanged(sensorSnapshot)
      Perception -> Nav : FusedObstacleSnapshot(snapshot)
      Obs -> Perception : ObstacleStateChanged(forwardSafe)
      Perception -> Nav : FusedObstacleSnapshot(forwardSafe)
      Nav -> Motors : MotionCommand(forward)
      Nav -> Clean : ResumeCleaningAfterManeuver()
      Clean -> CleanHW : CleaningCommand(active)
    end
  else [single maneuver]
    Obs -> Perception : ObstacleStateChanged(forwardBlockedNotSurrounded)
    Perception -> Nav : FusedObstacleSnapshot(forwardBlocked, notSurrounded)
    Nav -> Clean : SuspendCleaningForManeuver()
    Clean -> CleanHW : CleaningCommand(suspend)
    alt [typical prefer right]
      Nav -> Motors : MotionCommand(turnRight)
    else [A1 right not valid]
      Nav -> Motors : MotionCommand(turnLeft)
    end
    Obs -> Perception : ObstacleStateChanged(sensorSnapshot)
    Perception -> Nav : FusedObstacleSnapshot(snapshot)
    Obs -> Perception : ObstacleStateChanged(forwardSafe)
    Perception -> Nav : FusedObstacleSnapshot(forwardSafe)
    Nav -> Motors : MotionCommand(forward)
    Nav -> Clean : ResumeCleaningAfterManeuver()
    Clean -> CleanHW : CleaningCommand(active)
  end
  note over Nav, Motors : next: UC-02
end

@enduml
